<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Introduction - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.validate.introduction.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.validate.introduction.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.validate.html">Zend_Validate</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.validate.html">Zend_Validate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.validate.set.html">Standard Validation Classes</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.validate.introduction" class="section"><div class="info"><h1 class="title">Introduction</h1></div>
    

    <p class="para">
        The <span class="classname">Zend_Validate</span> component provides a set of commonly needed
        validators. It also provides a simple validator chaining mechanism by
        which multiple validators may be applied to a single datum in a
        user-defined order.
    </p>

    <div class="section" id="zend.validate.introduction.definition"><div class="info"><h1 class="title">What is a validator?</h1></div>
        

        <p class="para">
            A validator examines its input with respect to some requirements
            and produces a boolean result - whether the input successfully
            validates against the requirements. If the input does not meet the
            requirements, a validator may additionally provide information
            about which requirement(s) the input does not meet.
        </p>

        <p class="para">
            For example, a web application might require that a username be
            between six and twelve characters in length and may only contain
            alphanumeric characters. A validator can be used for ensuring that
            usernames meet these requirements. If a chosen username does not
            meet one or both of the requirements, it would be useful to know
            which of the requirements the username fails to meet.
        </p>
    </div>

    <div class="section" id="zend.validate.introduction.using"><div class="info"><h1 class="title">Basic usage of validators</h1></div>
        

        <p class="para">
            Having defined validation in this way provides the foundation for
            <span class="classname">Zend_Validate_Interface</span>, which defines two methods,
             <span class="methodname">isValid()</span> and  <span class="methodname">getMessages()</span>. The
             <span class="methodname">isValid()</span> method performs validation upon the provided
            value, returning <b><tt>TRUE</tt></b> if and only if the value passes
            against the validation criteria.
        </p>

        <p class="para">
            If  <span class="methodname">isValid()</span> returns <b><tt>FALSE</tt></b>, the
             <span class="methodname">getMessages()</span> returns an array of messages explaining
            the reason(s) for validation failure. The array keys are short
            strings that identify the reasons for validation failure, and the
            array values are the corresponding human-readable string messages.
            The keys and values are class-dependent; each validation class
            defines its own set of validation failure messages and the unique
            keys that identify them. Each class also has a const
            definition that matches each identifier for a validation failure
            cause.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The  <span class="methodname">getMessages()</span> methods return validation
                failure information only for the most recent
                 <span class="methodname">isValid()</span> call. Each call to
                 <span class="methodname">isValid()</span> clears any messages and errors caused by
                a previous  <span class="methodname">isValid()</span> call, because it&#039;s likely
                that each call to  <span class="methodname">isValid()</span> is made for a
                different input value.
            </p>
        </p></blockquote>

        <p class="para">
            The following example illustrates validation of an e-mail address:
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_EmailAddress();

if ($validator-&gt;isValid($email)) {
    // email appears to be valid
} else {
    // email is invalid; print the reasons
    foreach ($validator-&gt;getMessages() as $messageId =&gt; $message) {
        echo &quot;Validation failure &#039;$messageId&#039;: $message\n&quot;;
    }
}
</pre>

    </div>

    <div class="section" id="zend.validate.introduction.messages"><div class="info"><h1 class="title">Customizing messages</h1></div>
        

        <p class="para">
            Validate classes provide a  <span class="methodname">setMessage()</span> method with
            which you can specify the format of a message returned by
             <span class="methodname">getMessages()</span> in case of validation failure. The
            first argument of this method is a string containing the error
            message. You can include tokens in this string which will be
            substituted with data relevant to the validator. The token
            <em class="emphasis">%value%</em> is supported by all validators; this is
            substituted with the value you passed to  <span class="methodname">isValid()</span>.
            Other tokens may be supported on a case-by-case basis in each
            validation class. For example, <em class="emphasis">%max%</em> is a token
            supported by <span class="classname">Zend_Validate_LessThan</span>.
            The  <span class="methodname">getMessageVariables()</span> method returns an array
            of variable tokens supported by the validator.
        </p>

        <p class="para">
            The second optional argument is a string that identifies the
            validation failure message template to be set, which is useful when
            a validation class defines more than one cause for failure. If you
            omit the second argument,  <span class="methodname">setMessage()</span> assumes the
            message you specify should be used for the first message template
            declared in the validation class. Many validation classes only have
            one error message template defined, so there is no need to specify
            which message template you are changing.
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_StringLength(8);

$validator-&gt;setMessage(
    &#039;The string \&#039;%value%\&#039; is too short; it must be at least %min% &#039; .
    &#039;characters&#039;,
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator-&gt;isValid(&#039;word&#039;)) {
    $messages = $validator-&gt;getMessages();
    echo current($messages);

    // &quot;The string &#039;word&#039; is too short; it must be at least 8 characters&quot;
}
</pre>


        <p class="para">
            You can set multiple messages using the  <span class="methodname">setMessages()</span>
            method. Its argument is an array containing key/message pairs.
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_StringLength(array(&#039;min&#039; =&gt; 8, &#039;max&#039; =&gt; 12));

$validator-&gt;setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =&gt;
        &#039;The string \&#039;%value%\&#039; is too short&#039;,
    Zend_Validate_StringLength::TOO_LONG  =&gt;
        &#039;The string \&#039;%value%\&#039; is too long&#039;
));
</pre>


        <p class="para">
            If your application requires even greater flexibility with which it
            reports validation failures, you can access properties by the same
            name as the message tokens supported by a given validation class.
            The <span class="property">value</span> property is always available in a validator;
            it is the value you specified as the argument of
             <span class="methodname">isValid()</span>. Other properties may be supported on a
            case-by-case basis in each validation class.
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_StringLength(array(&#039;min&#039; =&gt; 8, &#039;max&#039; =&gt; 12));

if (!validator-&gt;isValid(&#039;word&#039;)) {
    echo &#039;Word failed: &#039;
        . $validator-&gt;value
        . &#039;; its length is not between &#039;
        . $validator-&gt;min
        . &#039; and &#039;
        . $validator-&gt;max
        . &quot;\n&quot;;
}
</pre>

    </div>

    <div class="section" id="zend.validate.introduction.static"><div class="info"><h1 class="title">Using the static is() method</h1></div>
        

        <p class="para">
            If it&#039;s inconvenient to load a given validation class and create an
            instance of the validator, you can use the static method
             <span class="methodname">Zend_Validate::is()</span> as an alternative invocation
            style. The first argument of this method is a data input value,
            that you would pass to the  <span class="methodname">isValid()</span> method. The
            second argument is a string, which corresponds to the basename of
            the validation class, relative to the <span class="classname">Zend_Validate</span>
            namespace. The  <span class="methodname">is()</span> method automatically loads the
            class, creates an instance, and applies the  <span class="methodname">isValid()</span>
            method to the data input.
        </p>

        <pre class="programlisting brush: php">
if (Zend_Validate::is($email, &#039;EmailAddress&#039;)) {
    // Yes, email appears to be valid
}
</pre>


        <p class="para">
            You can also pass an array of constructor arguments, if they
            are needed for the validator.
        </p>

        <pre class="programlisting brush: php">
if (Zend_Validate::is($value, &#039;Between&#039;, array(&#039;min&#039; =&gt; 1, &#039;max&#039; =&gt; 12))) {
    // Yes, $value is between 1 and 12
}
</pre>


        <p class="para">
            The  <span class="methodname">is()</span> method returns a boolean value, the same as
            the  <span class="methodname">isValid()</span> method. When using the static
             <span class="methodname">is()</span> method, validation failure messages are not
            available.
        </p>

        <p class="para">
            The static usage can be convenient for invoking a validator ad hoc,
            but if you have the need to run a validator for multiple inputs,
            it&#039;s more efficient to use the non-static usage, creating an
            instance of the validator object and calling its
             <span class="methodname">isValid()</span> method.
        </p>

        <p class="para">
            Also, the <span class="classname">Zend_Filter_Input</span> class allows you to
            instantiate and run multiple filter and validator classes on demand
            to process sets of input data. See
            <a href="zend.filter.input.html" class="link">Zend_Filter_Input</a>.
        </p>

        <div class="section" id="zend.validate.introduction.static.namespaces"><div class="info"><h1 class="title">Namespaces</h1></div>
            

            <p class="para">
                When working with self defined validators you can give a fourth parameter
                to  <span class="methodname">Zend_Validate::is()</span> which is the namespace
                where your validator can be found.
            </p>

            <pre class="programlisting brush: php">
if (Zend_Validate::is($value, &#039;MyValidator&#039;, array(&#039;min&#039; =&gt; 1, &#039;max&#039; =&gt; 12),
                      array(&#039;FirstNamespace&#039;, &#039;SecondNamespace&#039;)) {
    // Yes, $value is ok
}
</pre>


            <p class="para">
                <span class="classname">Zend_Validate</span> allows also to set namespaces as default.
                This means that you can set them once in your bootstrap and have not to give
                them again for each call of  <span class="methodname">Zend_Validate::is()</span>. The
                following code snippet is identical to the above one.
            </p>

            <pre class="programlisting brush: php">
Zend_Validate::setDefaultNamespaces(array(&#039;FirstNamespace&#039;, &#039;SecondNamespace&#039;));
if (Zend_Validate::is($value, &#039;MyValidator&#039;, array(&#039;min&#039; =&gt; 1, &#039;max&#039; =&gt; 12)) {
    // Yes, $value is ok
}

if (Zend_Validate::is($value,
                      &#039;OtherValidator&#039;,
                      array(&#039;min&#039; =&gt; 1, &#039;max&#039; =&gt; 12)) {
    // Yes, $value is ok
}
</pre>


            <p class="para">
                For your convenience there are following methods which allow the handling of
                namespaces:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <em class="emphasis"> <span class="methodname">Zend_Validate::getDefaultNamespaces()</span></em>:
                        Returns all set default namespaces as array.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis"> <span class="methodname">Zend_Validate::setDefaultNamespaces()</span></em>:
                        Sets new default namespaces and overrides any previous set. It accepts
                        either a string for a single namespace of an array for multiple namespaces.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis"> <span class="methodname">Zend_Validate::addDefaultNamespaces()</span></em>:
                        Adds additional namespaces to already set ones. It accepts either a string
                        for a single namespace of an array for multiple namespaces.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <em class="emphasis"> <span class="methodname">Zend_Validate::hasDefaultNamespaces()</span></em>:
                        Returns <b><tt>TRUE</tt></b> when one or more default namespaces are
                        set, and <b><tt>FALSE</tt></b> when no default namespaces are set.
                    </p>
                </li>
            </ul>
        </div>
    </div>

    <div class="section" id="zend.validate.introduction.translation"><div class="info"><h1 class="title">Translating messages</h1></div>
        

        <p class="para">
            Validate classes provide a  <span class="methodname">setTranslator()</span> method with
            which you can specify a instance of <span class="classname">Zend_Translate</span> which
            will translate the messages in case of a validation failure. The
             <span class="methodname">getTranslator()</span> method returns the set translator instance.
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_StringLength(array(&#039;min&#039; =&gt; 8, &#039;max&#039; =&gt; 12));
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; array(
            Zend_Validate_StringLength::TOO_SHORT =&gt; &#039;Translated \&#039;%value%\&#039;&#039;
        ),
        &#039;locale&#039; =&gt; &#039;en&#039;
    )
);

$validator-&gt;setTranslator($translate);
</pre>


        <p class="para">
            With the static  <span class="methodname">setDefaultTranslator()</span> method you can set
            a instance of <span class="classname">Zend_Translate</span> which will be used for all
            validation classes, and can be retrieved with
             <span class="methodname">getDefaultTranslator()</span>. This prevents you from setting a
            translator manually for all validator classes, and simplifies your code.
        </p>

        <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; array(
            Zend_Validate_StringLength::TOO_SHORT =&gt; &#039;Translated \&#039;%value%\&#039;&#039;
        ),
        &#039;locale&#039; =&gt; &#039;en&#039;
    )
);
Zend_Validate::setDefaultTranslator($translate);
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                When you have set an application wide locale within your registry, then this
                locale will be used as default translator.
            </p>
        </p></blockquote>

        <p class="para">
            Sometimes it is necessary to disable the translator within a validator.
            To archive this you can use the  <span class="methodname">setDisableTranslator()</span> method,
            which accepts a boolean parameter, and  <span class="methodname">translatorIsDisabled()</span>
            to get the set value.
        </p>

        <pre class="programlisting brush: php">
$validator = new Zend_Validate_StringLength(array(&#039;min&#039; =&gt; 8, &#039;max&#039; =&gt; 12));
if (!$validator-&gt;isTranslatorDisabled()) {
    $validator-&gt;setDisableTranslator();
}
</pre>


        <p class="para">
            It is also possible to use a translator instead of setting own messages with
             <span class="methodname">setMessage()</span>. But doing so, you should keep in mind, that the
            translator works also on messages you set your own.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.validate.html">Zend_Validate</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.validate.html">Zend_Validate</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.validate.set.html">Standard Validation Classes</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.validate.html">Zend_Validate</a></li>
  <li class="active"><a href="zend.validate.introduction.html">Introduction</a></li>
  <li><a href="zend.validate.set.html">Standard Validation Classes</a></li>
  <li><a href="zend.validate.validator_chains.html">Validator Chains</a></li>
  <li><a href="zend.validate.writing_validators.html">Writing Validators</a></li>
  <li><a href="zend.validate.messages.html">Validation Messages</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>